# 📘 TryOwBot WhatsApp API - Complete Documentation

## Nathan Groups India Private Limited
**Version:** 1.0 | **Date:** February 2026

---

## 📋 Table of Contents

1. [Overview](#overview)
2. [Common Mistakes & Solutions](#common-mistakes--solutions)
3. [API Configuration](#api-configuration)
4. [Authentication Flow](#authentication-flow)
5. [API Endpoints](#api-endpoints)
6. [Template Message Format](#template-message-format)
7. [Code Examples](#code-examples)
8. [Troubleshooting Guide](#troubleshooting-guide)
9. [Checklist for New Projects](#checklist-for-new-projects)

---

## Overview

TryOwBot is a WhatsApp Business API provider. This documentation covers the correct way to integrate their API into PHP applications.

**API Base URL:** `https://wa.tryowbot.com/`

---

## ⚠️ Common Mistakes & Solutions

### ❌ Mistake 1: Wrong API Endpoint

**Wrong:**
```php
curl_setopt($ch, CURLOPT_URL, 'https://api.tryowbot.com/v1/message/template');
```

**Correct:**
```php
curl_setopt($ch, CURLOPT_URL, 'https://wa.tryowbot.com/api/wpbox/sendtemplatemessage');
```

**Lesson:** Always verify the exact API endpoint from the official documentation or working code.

---

### ❌ Mistake 2: Using API Key Directly Instead of Login Token

**Wrong Approach:**
```php
// ❌ Direct API key in request - WRONG!
$wa_data = [
    'token' => 'zdzkzy9iwcFwQzAg2lwOrjvrCwcIXacuoaJ1bLsB661fd08a',
    'phone' => $phone,
    'template_name' => $template_name
];
```

**Correct Approach:**
```php
// ✅ First login to get dynamic token
$loginResponse = login($email, $password);
$token = $loginResponse['token']; // Dynamic token like "377|WKQEB1RuH2o9b01w..."

// Then use this token
$wa_data = [
    'token' => $token,  // Dynamic login token
    'phone' => $phone,
    'template_name' => $template_name
];
```

**Lesson:** TryOwBot requires **login authentication first** to get a session token. The API Key shown in dashboard is NOT directly used in requests.

---

### ❌ Mistake 3: Wrong Parameter Format

**Wrong:**
```php
// ❌ Simple array - WRONG!
$template_params = [
    'John Doe',
    'Software Developer',
    '10 Feb 2026'
];
```

**Correct:**
```php
// ✅ Proper format with type specification
$body_params = [
    ['type' => 'text', 'text' => 'John Doe'],
    ['type' => 'text', 'text' => 'Software Developer'],
    ['type' => 'text', 'text' => '10 Feb 2026']
];

$components = [
    [
        'type' => 'body',
        'parameters' => $body_params
    ]
];
```

**Lesson:** Each parameter must have `type` and `text` keys inside the `components` array.

---

### ❌ Mistake 4: Template Not Created in WhatsApp Business

**Problem:** Code is correct but message not sending.

**Reason:** The template name used in code doesn't exist in WhatsApp Business Manager.

**Solution:**
1. Go to Meta Business Suite → WhatsApp Manager → Message Templates
2. Create template with exact name used in code
3. Wait for approval (Status: "In review" → "Active")
4. Only then the API will work

**Lesson:** Always create and get approval for templates BEFORE writing code.

---

### ❌ Mistake 5: Wrong Template Language Code

**Wrong:**
```php
'template_language' => 'en'  // ❌ May not match
```

**Correct:**
```php
'template_language' => 'en_US'  // ✅ Exact match with template
```

**Lesson:** Language code must EXACTLY match what's shown in WhatsApp Business Manager (e.g., `en_US`, `en_GB`, `ta`, `hi`).

---

## API Configuration

### Required Credentials

| Credential | Where to Find | Example |
|------------|---------------|---------|
| Email | TryOwBot Login | nathancareline@gmail.com |
| Password | TryOwBot Login | your_password |
| API Key | Dashboard → Account → API Keys | zdzkzy9iwcFwQzAg... |

### Important URLs

| Purpose | URL |
|---------|-----|
| API Base | `https://wa.tryowbot.com/` |
| Login | `https://wa.tryowbot.com/api/login` |
| Send Template | `https://wa.tryowbot.com/api/wpbox/sendtemplatemessage` |
| Send Message | `https://wa.tryowbot.com/api/wpbox/sendmessage` |
| Get Templates | `https://wa.tryowbot.com/api/wpbox/getTemplates?token=xxx` |

---

## Authentication Flow

```
┌─────────────────────────────────────────────────────────────┐
│                    AUTHENTICATION FLOW                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Step 1: Login Request                                       │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ POST https://wa.tryowbot.com/api/login              │    │
│  │ Body: email=xxx&password=xxx                        │    │
│  └─────────────────────────────────────────────────────┘    │
│                          ↓                                   │
│  Step 2: Receive Token                                       │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ Response: {"token": "377|WKQEB1RuH2o9...", ...}     │    │
│  └─────────────────────────────────────────────────────┘    │
│                          ↓                                   │
│  Step 3: Use Token in API Calls                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ POST https://wa.tryowbot.com/api/wpbox/send...      │    │
│  │ Body: {"token": "377|WKQEB1RuH2o9...", ...}         │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

---

## API Endpoints

### 1. Login API

```php
POST https://wa.tryowbot.com/api/login

// Request (form-urlencoded)
$postData = [
    'email' => 'your_email@gmail.com',
    'password' => 'your_password'
];

// Response
{
    "status": true,
    "token": "377|WKQEB1RuH2o9b01wC2jUeIMEgcmrsakZGDOaemqc615b131e",
    "id": 166,
    "name": "Nathanhealth Plus",
    "email": "nathancareline@gmail.com"
}
```

### 2. Send Template Message API

```php
POST https://wa.tryowbot.com/api/wpbox/sendtemplatemessage
Content-Type: application/json

// Request
{
    "token": "377|WKQEB1RuH2o9...",
    "phone": "919876543210",
    "template_name": "interview_confirmation",
    "template_language": "en_US",
    "components": [
        {
            "type": "body",
            "parameters": [
                {"type": "text", "text": "John Doe"},
                {"type": "text", "text": "Software Developer"}
            ]
        }
    ]
}
```

### 3. Send Simple Message API

```php
POST https://wa.tryowbot.com/api/wpbox/sendmessage
Content-Type: application/json

// Request
{
    "token": "377|WKQEB1RuH2o9...",
    "phone": "919876543210",
    "message": "Hello! This is a test message."
}
```

### 4. Get Templates API

```php
GET https://wa.tryowbot.com/api/wpbox/getTemplates?token=377|WKQEB1RuH2o9...

// Response
{
    "status": "success",
    "templates": [
        {
            "name": "interview_confirmation",
            "status": "APPROVED",
            "language": "en_US"
        }
    ]
}
```

---

## Template Message Format

### Components Structure

```php
$components = [
    // Header (optional) - for image/document/video
    [
        'type' => 'header',
        'parameters' => [
            [
                'type' => 'image',
                'image' => ['link' => 'https://example.com/image.jpg']
            ]
        ]
    ],
    
    // Body (required) - main message variables
    [
        'type' => 'body',
        'parameters' => [
            ['type' => 'text', 'text' => 'Variable 1'],
            ['type' => 'text', 'text' => 'Variable 2'],
            ['type' => 'text', 'text' => 'Variable 3']
        ]
    ],
    
    // Button (optional) - for dynamic URL buttons
    [
        'type' => 'button',
        'sub_type' => 'url',
        'index' => '0',
        'parameters' => [
            ['type' => 'text', 'text' => 'token123']
        ]
    ]
];
```

### Parameter Types

| Type | Usage | Example |
|------|-------|---------|
| text | Text variables | `['type' => 'text', 'text' => 'John']` |
| image | Header image | `['type' => 'image', 'image' => ['link' => 'url']]` |
| document | Header PDF | `['type' => 'document', 'document' => ['link' => 'url']]` |
| video | Header video | `['type' => 'video', 'video' => ['link' => 'url']]` |

---

## Code Examples

### Complete Working Example - TryOwBotAPI Class Usage

```php
<?php
// Include the API class
include 'TryOwBot_WhatsApp_API.php';

// Initialize
$whatsapp = new TryOwBotAPI();

// Example 1: Send Interview Confirmation
$result = $whatsapp->sendInterviewConfirmation(
    '9876543210',           // Phone
    'John Doe',             // Candidate Name {{1}}
    'Software Developer',   // Job Title {{2}}
    '10 Feb 2026',          // Date {{3}}
    '10:00 AM',             // Time {{4}}
    'Nathan Groups, Chennai', // Venue {{5}}
    'Aadhar, PAN, Resume',  // Documents {{6}}
    'HR - 9876543210'       // Contact {{7}}
);

if ($result['success']) {
    echo "Message sent successfully!";
} else {
    echo "Failed: " . $result['message'];
}

// Example 2: Send Payment Invoice
$result = $whatsapp->sendPaymentInvoice(
    '9876543210',   // Phone
    '₹500',         // Amount {{1}}
    '19 Jan 2026',  // Date {{2}}
    'INV123_token'  // Button URL token
);

// Example 3: Send OTP
$result = $whatsapp->sendOTP('9876543210', '123456');

// Example 4: Send Simple Template
$result = $whatsapp->sendTemplate(
    '9876543210',
    'template_name',
    'en_US',
    ['Param1', 'Param2', 'Param3']
);
?>
```

### Manual cURL Implementation

```php
<?php
// Step 1: Login
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://wa.tryowbot.com/api/login');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'email' => 'your_email@gmail.com',
    'password' => 'your_password'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
$token = $data['token'];

// Step 2: Send Template Message
$payload = [
    'token' => $token,
    'phone' => '919876543210',
    'template_name' => 'interview_confirmation',
    'template_language' => 'en_US',
    'components' => [
        [
            'type' => 'body',
            'parameters' => [
                ['type' => 'text', 'text' => 'John Doe'],
                ['type' => 'text', 'text' => 'Software Developer'],
                ['type' => 'text', 'text' => '10 Feb 2026'],
                ['type' => 'text', 'text' => '10:00 AM'],
                ['type' => 'text', 'text' => 'Chennai Office'],
                ['type' => 'text', 'text' => 'Aadhar, PAN'],
                ['type' => 'text', 'text' => 'HR - 9876543210']
            ]
        ]
    ]
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://wa.tryowbot.com/api/wpbox/sendtemplatemessage');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Accept: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);

print_r(json_decode($response, true));
?>
```

---

## Troubleshooting Guide

### Error: "GET method is not supported"

**Cause:** Token is null/empty, causing malformed request

**Solution:**
1. Check login credentials
2. Verify token is received before sending
3. Add token validation:
```php
$token = $this->getToken();
if (!$token) {
    return ['success' => false, 'message' => 'Login failed'];
}
```

### Error: "Template not found"

**Cause:** Template doesn't exist or name mismatch

**Solution:**
1. Check template exists in WhatsApp Business Manager
2. Verify exact template name (case-sensitive)
3. Check template is APPROVED (not "In review")

### Error: "Invalid phone number"

**Cause:** Phone format incorrect

**Solution:**
```php
// Always format phone number
$phone = preg_replace('/[^0-9]/', '', $phone);
if (strlen($phone) == 10) {
    $phone = '91' . $phone; // Add country code
}
```

### Error: "Parameter count mismatch"

**Cause:** Template has 7 variables but code sends 5

**Solution:** Match exact number of parameters with template

---

## ✅ Checklist for New Projects

### Before Writing Code:

- [ ] Get TryOwBot account credentials (email, password)
- [ ] Note down API Key from dashboard
- [ ] Create required templates in WhatsApp Business Manager
- [ ] Wait for template approval
- [ ] Note exact template names and language codes
- [ ] Count number of variables in each template

### While Writing Code:

- [ ] Use correct API base URL: `https://wa.tryowbot.com/`
- [ ] Implement login flow to get token
- [ ] Use dynamic token (not static API key)
- [ ] Format phone numbers with country code
- [ ] Use correct parameter format with `type` and `text`
- [ ] Match template_language exactly

### Testing:

- [ ] Test login API separately first
- [ ] Verify token is received
- [ ] Test with getTemplates API to confirm template exists
- [ ] Send test message to your own number
- [ ] Check whatsapp_log.txt for debugging

### Production:

- [ ] Add error logging
- [ ] Handle token expiry (refresh after 23 hours)
- [ ] Add retry mechanism for failed requests
- [ ] Monitor message delivery status

---

## 📁 Required Files

| File | Purpose |
|------|---------|
| `TryOwBot_WhatsApp_API.php` | Main API class with all methods |
| `db_config.php` | Database connection |
| `save_interview.php` | Interview scheduler with WhatsApp |
| `test_debug.php` | Debug and testing tool |

---

## 📞 Support

- **TryOwBot Dashboard:** https://wa.tryowbot.com/
- **WhatsApp Business Manager:** https://business.facebook.com/
- **API Documentation:** TryOwBot Dashboard → Documentation

---

## 📝 Version History

| Version | Date | Changes |
|---------|------|---------|
| 1.0 | Feb 2026 | Initial documentation |

---

**Document Created:** February 3, 2026  
**Author:** Nathan Groups Development Team